JBoss Community Archive (Read Only)

RHQ 4.7

Design-Remote API

Overview

A significant difference in approach was the initial approach to expose the Local interfaces nearly completely.  In this second go there is a goal to provide a smaller set of Remote interfaces that remain robust yet are easier to use for the vast majority of integration use cases.  It will de-emphasize administration and focus on operational aspects of integration. This set of remopte interfaces must support the CLI, as well as support as many of our known use cases as possible.  A more general goal is to be able to build powerful applications, both automation and GUI oriented, on this set of services.  Although, it is not the goal to be able to implement the full JON GUI on this set of services.
These remote interfaces will be made available via JBoss Remoting for Java clients, and JAX-WS (JBossWS) for non-Java clients (although nothing prevents a Java WS client as well, it's just not obvious what the need would be given JBoss remoting).

Approach and Conventions

  • XxManagerRemote and XxManagerLocal interfaces will be implemented by the same impl XxManagerBean

    • Utilize the current impls while providing a more consistent, convenient, and cohesive remote interface.

    • Current locals have a lot of specific support for RHQ and lack consistency due to organic growth

  • Simplify API by providing simple services complemented by rich, multi-purpose counterparts for complex needs

  • Prefer paginated services

  • Other than login specific services, all services supply logged-in Subject as initial parameter for authorization

  • Carefully consider the needs for Administration services

    • Judiciously provide CRUD; I expect that certain Add/Create services will be needed. Not sure of the use cases. Delete/Purge probably less so.

  • Simple getters

    • Typically Provide getter by Id

    • Will not allow for optional data

    • To get optional data use 'find' or make a follow-on request for that specific data (if the service exists)

  • Convenience routines

    • Be very judicious since we can't predict what will be generally convenient

    • Only add if currently supported in SLSB and obviously generally useful

    • rich find is always possible

  • getAll as a standard convenience service

    • Rejected - too unconstrained

  • Avoid constructs tied to our UI implementation

    • e.g. don't expose things like: List<AvailabilityPoint> getAvailabilityPointsForResourceGroup(...)

  • Find Criteria

    • takes the entity and for supported fields, uses set values as search criteria

    • must be jdoc'd to explicitly define supported search criteria (fields, values (explicit, pattern, etc)

  • Optional Data

    • Allows the caller to specify (normally lazily loaded) data to be optionally returned.

    • Provides a consistent way to provide deterministic results

    • Embedded in PageControl with vararg setter

    • an Enum defined by the relevant remote interface of supported data

  • Ordering results

    • Required for all PageControlled queries

    • Will require us to consolidate field references across the query base

  • Objects or primitives (Integer or ints)

    • no real opinion, using primitives

  • Exceptions

    • Most remote services will throw a checked exception

    • One of the following RHQ Exceptions Create/Delete/Fetch/Update/Login/Deploy

    • Since Local and Remote interface have single imple they may share entry points, so no remote-specific exceptions

    • ensure as we go that the impls are actually handling/throwing exceptions as consistently as possible

  • No overloading, use different service names for each service within a manager.

    • More clear for various remote API invocation types

    • Better for CLI auto-complete

Planned Remotes

Use Case valueY(in)/#(in, use case number)/N(out)/M(maybe, proposed but no current use case)/
Status value = P(pass)/F(fail) blank indicates untested

Remote Interface

Review

Test Status

Service

AlertDefinitionManagerRemote

Use Case

Status

Service

 

 

AlertDefinition getAlertDefinition(Subject sessionSubject, int alertDefinitionId ) throws FetchException

 

 

PageList<AlertDefinition> findAlertDefinitions(Subject sessionSubject, AlertDefinition criteria PageControl pc ) throws FetchException

  • Optional Data

    • none

  • Criteria

    • id

    • name (pattern)

    • resourceId

    • resourceType

AlertManagerRemote

Use Case

Status

Service

2

 

PageList<Alert> findAlerts(Subject sessionSubject, Alert criteria, int[] resourceIds, long beginTime, long endTime, PageControl pc) throws FetchException

  • Optional Data

    • conditionLogs (Set<AlertConditionLog>)

  • Criteria

    • id

    • priority

    • definitionId

AvailabilityManagerRemote

Use Case

Status

Service

 

 

PageList<Availability> getAvailabilityForResource(Subject sessionSubject, int resourceId, PageControl pc) throws FetchException

 

 

Availability getCurrentAvailabilityForResource(Subject sessionSubject, int resourceId) throws FetchException

CallTimeDataManagerRemote

Use Case

Status

Service

 

 

PageList<CallTimeDataComposite> getCallTimeDataForResource(Subject sessionSubject, int measurementScheduleId, long beginTime, long endTime, PageControl pageControl) throws FetchException

 

 

PageList<CallTimeDataComposite> getCallTimeDataForCompatibleGroup(Subject sessionSubject, int groupId, int measurementDefinitionId, long beginTime, long endTime, PageControl pageControl) throws FetchException

ChannelManagerRemote

Use Case

Status

Service

8

 

void addPackageVersionsToChannel(Subject sessionSubject, int channelId, int[] packageVersionIds) throws UpdateException

8

 

Channel createChannel(Subject sessionSubject, Channel channel) throws CreateException

8

 

void deleteChannel(Subject sessionSubject, int channelId) throws DeleteException

8

 

Channel getChannel(Subject sessionSubject, int channelId) throws FetchException

8

 

PageList<Channel> findChannels(Subject sessionSubject, Channel criteria, PageControl pc) throws FetchException

  • Optional Data

    • channelPackageVersions (Set<ChannelPackageVersion>)

  • Criteria

    • id

8

 

PageList<PackageVersion> findPackageVersionsInChannel(Subject sessionSubject, int channelId, PackageVersion criteria, PageControl pc) throws FetchException

  • Optional Data

    • extraProperties (Configuration)

    • channelPackageVersions (Set<ChannelPackageVersion>)

    • productVersionPackageVersions (Set<ProductVersionPackageVersion>)

  • Criteria

    • id

    • name (filter)

8

 

Channel updateChannel(Subject sessionSubject, Channel newChannel) throws UpdateException

ConfigurationManagerRemote

Enum ConfigurationType
CURRENT
LIVE

Use Case

Status

Service

 

 

AggregatePluginConfigurationUpdate getAggregatePluginConfigurationUpdate(Subject sessionSubject, int configurationUpdateId) throws FetchException

  • will load configurationUpdates (List<PluginConfigurationUpdate>)

 

 

AggregateResourceConfigurationUpdate getAggregateResourceConfigurationUpdate(Subject sessionSubject, int configurationUpdateId) throws FetchException

  • will load configurationUpdates (List<ResourceConfigurationUpdate>)

 

 

Configuration getConfiguration(Subject sessionSubject, int configurationId) throws FetchException

3

 

Configuration getPluginConfiguration(Subject sessionSubject, int resourceId, ConfigurationType type) throws FetchException

3

 

Configuration getResourceConfiguration(Subject sessionSubject, int resourceId, ConfigurationType type) throws FetchException

 

 

PluginConfigurationUpdate getLatestPluginConfigurationUpdate(Subject sessionSubject, int resourceId) throws FetchException

 

 

PluginConfigurationUpdate getLatestResourceConfigurationUpdate(Subject sessionSubject, int resourceId) throws FetchException

3

 

boolean isResourceConfigurationUpdateInProgress(Subject sessionSubject, int resourceId) throws FetchException

 

 

boolean isAggregateResourceConfigurationUpdateInProgress(Subject sessionSubject, int resourceGroupId) throws FetchException

 

 

int scheduleAggregatePluginConfigurationUpdate(Subject sessionSubject, int compatibleGroupId, Map<Integer, Configuration> newResourcePluginConfigurationMap) throws UpdateException

 

 

int scheduleAggregateResourceConfigurationUpdate(Subject sessionSubject, int compatibleGroupId, Map<Integer, Configuration> newResourceConfigurationMap) throws UpdateException

3

 

PluginConfigurationUpdate updatePluginConfiguration(Subject sessionSubject, int resourceId, Configuration newConfiguration) throws UpdateException

3

 

ResourceConfigurationUpdate updateResourceConfiguration(Subject sessionSubject, int resourceId, Configuration newConfiguration) throws UpdateException

ContentManagerRemote

Use Case

Status

Service

8

 

PackageVersion createPackageVersion(Subject sessionSubject, String packageName, int packageTypeId, String version, int architectureId, InputStream packageBitStream) throws CreateException

8

 

void deletePackages(Subject sessionSubject, int resourceId, int[] installedPackageIds, String requestNotes) throws DeleteException

8

 

void deployPackages(Subject sessionSubject, int[] resourceIds, int[] packageVersionIds) throws DeployException

EventManagerRemote

Use Case

Status

Service

5

 

PageList<EventComposite> getEventsForResource(Subject sessionSubject, int resourceId, long begin, long end, EventSeverity severity, String source, String detail, PageControl pc) throws FetchException

 

 

PageList<EventComposite> getEventsForAutoGroup(Subject sessionSubject, int groupId, long begin, long end, EventSeverity severity, int parentId, String source, String detail, PageControl) throws FetchException

 

 

PageList<EventComposite> getEventsForCompGroup(Subject sessionSubject, int groupId, long begin, long end, EventSeverity severity, int eventId, String source, String detail, PageControl pc)
pc) throws FetchException

 

 

EventSeverity[] getSeverityBuckets(Subject sessionSubject, int resourceId, long begin, long end, int numBuckets) throws FetchException

 

 

EventSeverity[] getSeverityBucketsForAutoGroup(Subject sessionSubject, int parentId, long begin, long end, int numBuckets) throws FetchException

 

 

EventSeverity[] getSeverityBucketsForCompGroup(Subject sessionSubject, int groupId, long begin, long end, int numBuckets) throws FetchException

 

 

PageList<EventComposite> findEvents(Subject sessionSubject, long begin, long end, Event criteria, PageControl pc) throws FetchException

  • Criteria

    • id (event.id)

    • Severity (event.severity)

    • Detail (event.detail)

MeasurementBaselineManagerRemote

Use Case

Status

Service

 

 

List<MeasurementBaseline> getBaselinesForResource(Subject sessionSubject, int resourceId ) throws FetchException

MeasurementDataManagerRemote

Use Case

Status

Service

 

 

MeasurementAggregate getAggregate(Subject sessionSubject, int scheduleId, long startTime, long endTime) throws FetchException

4

 

List<MeasurementDataTrait> getTrait(Subject sessionSubject, int resourceId, int definitionId) throws FetchException

4

 

List<MeasurementDataTrait> getCurrentTraits(Subject sessionSubject, int resourceId) throws FetchException

4

 

Set<MeasurementData> getLiveData(Subject sessionSubject, int resourceId, int[] definitionIds) throws FetchException

 

 

List<List<MeasurementDataNumericHighLowComposite>> getDataForCompatibleGroup(Subject sessionSubject, int groupId, int definitionId, long beginTime, long endTime, int numPoints, boolean groupAggregateOnly) throws FetchException

4

 

List<List<MeasurementDataNumericHighLowComposite>> getDataForResource(Subject sessionSubject, int resourceId, int[] definitionIds, long beginTime, long endTime, int numPoints) throws FetchException

MeasurementDefinitionManagerRemote

Use Case

Status

Service

 

 

MeasurementDefinition getMeasurementDefinition(Subject sessionSubject, int definitionId) throws FetchException

7

 

PageList<MeasurementDefinition> findMeasurementDefinitions(Subject sessionSubject, MeasurementDefinition criteria, PageControl pc) throws FetchException

  • Optional Data

    • resourceType (ResourceType)

    • schedules (List<MeasurementSchedule>)

  • Criteria

    • id

    • resourceType

    • dataType

    • scheduleIds (can we handle a list/IN in the generator?)

MeasurementProblemManagerRemote

Use Case

Status

Service

 

 

PageList<ProblemResourceComposite> getProblemResources(Subject sessionSubject, long beginTime, int maxResources, PageControl pc) throws FetchException

MeasurementScheduleManagerRemote

Use Case

Status

Service

 

 

void disableSchedules(Subject sessionSubject, int resourceId, int[] definitionIds ) throws UpdateException

 

 

void disableSchedulesForCompatibleGroup(Subject sessionSubject, int groupId, int[] measurementDefinitionIds ) throws UpdateException

 

 

void enableSchedules(Subject sessionSubject, int resourceId, int[] definitionIds ) throws UpdateException

 

 

void enableSchedulesForCompatibleGroup(Subject sessionSubject, int groupId, int[] definitionIds ) throws UpdateException

 

 

PageList<MeasurementScheduleComposite> getDefaultMeasurementSchedulesForResourceType(Subject subject, int resourceTypeId, PageControl pageControl)

 

 

List<MeasurementSchedule> getMeasurementSchedulesByDefinitionIdAndResources(Subject subject, int definitionId, List<Resource> resources)

 

 

PageList<MeasurementScheduleComposite> getMeasurementSchedulesForAutoGroup(Subject subject, int parentId, int childType, PageControl pageControl)

 

 

public PageList<MeasurementScheduleComposite> getMeasurementSchedulesForCompatGroup(Subject subject, int groupId, PageControl pageControl)

 

 

PageList<MeasurementScheduleComposite> getMeasurementSchedulesForResource(Subject subject, int resourceId, DataType dataType, PageControl pageControl)

 

 

List<MeasurementSchedule> getSchedulesByIds(Subject subject, Collection<Integer> ids)

  • added Subject param

OperationManagerRemote

Use Case

Status

Service

1

 

void cancelOperationHistory(Subject sessionSubject, int historyId, boolean ignoreAgentErrors)

1

 

void deleteOperationHistory(Subject sessionSubject, int historyId, boolean purgeInProgress)

1

 

void unscheduleResourceOperation(Subject sessionSubject, String jobId, int resourceId) throws UnscheduleException

 

 

void unscheduleGroupOperation(Subject sessionSubject, String jobId, int resourceGroupId) throws UnscheduleException

 

 

ResourceOperationSchedule scheduleResourceOperation(Subject sessionSubject, int resourceId, String operationName, long delay, long repeatInterval, int repeatCount, int timeout, Configuration parameters, String description) throws ScheduleException

 

 

GroupOperationSchedule scheduleGroupOperation(Subject sessionSubject, int groupId, int[] executionOrderResourceIds,boolean haltOnFailure, String operationName, Configuration parameters, long delay, long repeatInterval, int repeatCount, int timeout, String description) throws ScheduleException

M

 

OperationHistory getOperationHistoryByHistoryId(Subject sessionSubject, int historyId)

M

 

OperationHistory getOperationHistoryByJobId(Subject sessionSubject, String historyJobId)

1

 

PageList<ResourceOperationHistory> findOperationHistories(Subject sessionSubject, ResourceOperationHistory criteria, PageControl pc) throws FetchException

  • Criteria

    • Status (ResourceOperationHistory.status)

    • CreatedTime (ResourceOperationHistory.createdTime)

    • jobName (ResourceOperationHistory.jobName)

    • jobGroup (ResourceOperationHistory.jobGroup)

    • ResourceId (ResourceOperationHistory.resource.id)

ResourceGroupManagerRemote

Use Case

Status

Service

 

 

void addResourcesToGroup(Subject sessionSubject, int groupId, int[] resourceIds) throws UpdateException

 

 

ResourceGroup createResourceGroup(Subject sessionSubject, ResourceGroup resourceGroup) throws CreateException

 

 

void deleteResourceGroup(Subject sessionSubject, int groupId) throws DeleteException

 

 

ResourceGroup getResourceGroup(Subject sessionSubject, int groupId) throws FetchException

 

 

ResourceGroupComposite getResourceGroupComposite(Subject sessionSubject, int groupId) throws FetchException

 

 

PageList<ResourceGroup> getResourceGroupsForRole(Subject sessionSubject, int roleId, PageControl pageControl) throws FetchException

 

 

PageList<ResourceGroup> findResourceGroups(Subject sessionSubject, ResourceGroup criteria, PageControl pc) throws FetchException

  • OptionalData - probable

    • implicitResources (Set<Resource>)

    • explicitResources (Set<Resource>)

    • roles (Set<Role>)

  • OptionalData - possible

    • modifiedBy (Subject)

    • operationHistories (List<GroupOperationHistory>)

  • Criteria

    • id

    • groupCategory

    • resourceCategory

    • resourceType

    • name (filter)

    • resourceId

 

 

PageList<ResourceGroupComposite> findResourceGroupComposites(Subject sessionSubject, ResourceGroup criteria, PageControl pc) throws FetchException

  • OptionalData - same as findResourceGroups

  • Criteria - same as findResourceGroups

 

 

void removeResourcesFromGroup(Subject sessionSubject, int groupId, int[] resourceIds) throws UpdateException

 

 

void setRecursive(Subject sessionSubject, int groupId, boolean isRecursive) throws UpdateException

 

 

ResourceGroup updateResourceGroup(Subject sessionSubject, newResourceGroup) throws UpdateException

Notes:

  • Stuff not exposed at this time:

    • group definition

ResourceManagerRemote

Use Case

Status

Service

 

 

Resource getResource(Subject sessionSubject, int resourceId) throws FetchException

 

 

List<Resource> getResourceLineage(Subject sessionSubject, int resourceId) throws FetchException

 

 

PageList<Resource> findResources(Subject sessionSubject, Resource criteria, PageControl pc) throws FetchException

  • OptionalData - probable

    • agent (Agent)

    • availability (List<Availability>)

    • currentAvailability (ResourceAvailability)

    • explicitGroups (Set<ResourceGroup>)

    • implicitGroups (Set<ResourceGroup>)

    • parentResource (Resource)

    • pluginConfiguration (Configuration)

    • productVersion (ProductVersion)

    • resourceConfiguration (Configuration)

    • resourceErrors (List<ResourceError>)

    • resourceType (ResourceType)

  • OptionalData - possible

    • alertDefinitions (Set<AlertDefinitions>)

    • contentServiceRequests (List<ContentServiceRequest>)

    • createChildResourceRequests (List<CreateResourceHistory>)

    • deleteResourceRequests (List<DeleteResourceHistory>)

    • eventSources (Set<EventSource>)

    • installedPackages (Set<InstalledPackage>)

    • installedPackageHistory (List<InstalledPackageHistory>)

    • modifiedBy (Subject)

    • operationHistories (List<ResourceOperationHistory>)

    • pluginConfigurationUpdates (List<PluginConfigurationUpdate>)

    • resourceChannels (Set<ResourceChannel>)

    • resourceConfigurationUpdates (List<ResourceConfigurationUpdate>)

    • schedules (Set<MeasurementSchedule>)

  • Criteria

    • id

    • String (Resource.description) Substring Match

    • InventoryStatus (Resource.inventoryStatus)

    • String (Resource.name) Substring Match

    • ParentResource (Resource.parentResource.id)

    • ResourceType (Resource.resourceType.id)

 

 

PageList<Resource> findResourceChildren(Subject sessionSubject, Resource criteria, PageControl pc) throws FetchException

  • OptionalData (for each child)

    • Same as findResources

  • Criteria (for child)

    • id

    • String (Resource.description) Substring Match

    • InventoryStatus (Resource.inventoryStatus)

    • String (Resource.name) Substring Match

    • ResourceType (Resource.resourceType.id)

 

 

void uninventoryResources(Subject sessionSubject, int[] resourceIds) throws DeleteException

RoleManagerRemote

Use Case

Status

Service

 

 

Subject getRole(Subject sessionSubject, int roleId) throws FetchException

 

 

PageList<Role> getSubjectAssignedRoles(Subject sessionSubject, int subjectId, PageControl pc ) throws FetchException

 

 

PageList<Role> getSubjectUnassignedRoles(Subject sessionSubject, int subjectId, PageControl pc ) throws FetchException

 

 

PageList<Role> findRoles(Subject sessionSubject, Role criteria, PageControl pc) throws FetchException

7

 

void addRolesToSubject(Subject sessionSubject, int subjectId, int[] roleIds) throws UpdateException

7

 

void addSubjectsToRole(Subject sessionSubject, int roleId, int[] subjectIds) throws UpdateException

7

 

void removeRolesFromSubject(Subject sessionSubject, int subjectId, int[] roleIds) throws UpdateException

7

 

void removeSubjectsFromRole(Subject sessionSubject, int roleId, int[] subjectIds) throws UpdateException

 

 

void addRolesToGroup(Subject sessionSubject, int groupId, int[] roleIds) throws UpdateException

 

 

void addGroupsToRole(Subject sessionSubject, int roleId, int[] groupIds) throws UpdateException

 

 

void removeRolesFromGroup(Subject sessionSubject, int groupId, int[] roleIds) throws UpdateException

 

 

void removeGroupsFromRole(Subject sessionSubject, int roleId, int[] groupIds) throws UpdateException

SubjectManagerRemote

Use Case

Status

Service

7

 

void changePassword(Subject sessionSubject, String username, String password) throws UpdateException

7

 

void createPrincipal(Subject sessionSubject, String username, String password) throws CreateException

7

 

Subject createSubject(Subject sessionSubject, Subject subject) throws CreateException

7

 

void deleteSubjects(Subject sessionSubject, int[] subjectIds) throws DeleteException

7

 

Subject getSubject(Subject sessionSubject, int subjectId ) throws FetchException

c

 

Subject getSubjectByName(Subject sessionSubject, String username ) throws FetchException

7

 

PageList<Subject> findSubjects(Subject sessionSubject, Subject criteria, PageControl pc) throws FetchException

  • Optional Data

    • roles (Set<Role>)

  • Criteria

    • id

    • name (substring)

    • firstName

    • lastName

    • emailAddress

  • Sort

    • name

    • firstName

    • lastName

    • emailAddress

Y

 

boolean isLoggedIn(String username) throws FetchException

Y

 

Subject login(String username, String password) throws LoginException

Y

 

void logout(int sessionId)

7

 

Subject updateSubject(Subject sessionSubject, Subject newSubject) throws UpdateException

h41. (Perhaps) notable exceptions to current API

  • AutoGroup

  • Group Definition

  • Permissions stuff

  • Resource HealthSummary stuff

Locals without planned remotes at this time:

Remote Interface

Notes

AffinityGroupManagerLocal

Not necessary, administration via GUI

AgentManagerLocal

Not necessary, administration via GUI

AgentStatusManagerLocal

Server impl, no exposure necessary

AlertConditionCacheManagerLocal

Server impl, no exposure necessary

AlertConditionLogManagerLocal

Server impl, no exposure necessary

AlertConditionManagerLocal

Not necessary to see alert conditions, just alert firings/history

AlertDampeningManagerLocal

Server impl, no exposure necessary

AlertNotificationManagerLocal

Not necessary to manipulate notifications

AlertTemplateManagerLocal

Not necessary to manipulate alert templates

AuthorizationManagerRemote

Logged in user will be denied services if they don't have the permissions necessary. Inspection of authorization information may not be needed.

CachedConditionManagerLocal

Server impl, no exposure necessary

CachedConditionProducerLocal

Server impl, no exposure necessary

CacheConsistencyManagerLocal

Server impl, no exposure necessary

ConfigurationMetadataManagerLocal

Do we need to be able to update config, leaning against...

ContentSourceManagerLocal

Not necessary, administration via GUI

ContentUIManagerLocal

Not necessary, administration via GUI

EmailManagerLocal

Server impl, no exposure necessary

EntityManagerFacadeLocal

Server impl, no exposure necessary

FailoverListManagerLocal

Not necessary, administration via GUI

GroupDefinitionExpressionBuilderManagerLocal

Not necessary, GUI support

GroupDefinitionManagerLocal

Not necessary, administration via GUI

MeasurementCompressionManagerLocal

Server impl, no exposure necessary

PartitionEventManagerLocal

Not necessary, administration via GUI

PerspectiveManagerLocal

Server impl, no exposure necessary

ProductVersionManagerLocal

Not necessary, administration via GUI

ResourceBossLocal

??? maybe need the ability to get an Inventory summary for the user ?

ResourceMetadataManagerLocal

Server impl, no exposure necessary

ResourceFactoryManagerLocal

Not necessary, administration via GUI

SchedulerLocal

Server impl, no exposure necessary

ServerManagerLocal

Not necessary, administration via GUI

SystemManagerLocal

Server impl, no exposure necessary ??? getVersion?

 

 

JBoss.org Content Archive (Read Only), exported from JBoss Community Documentation Editor at 2020-03-12 13:56:56 UTC, last content change 2012-11-19 22:07:16 UTC.